Service Manager powered by HEAT

Using Field References

•About the Current Business Object

•Referencing a Field in the Current Business Object

About the Current Business Object

Most expressions refer to fields of business objects.

In business rules, the current business object is the instance of the business object that contains the business rule. For example, if a business rule is part of the definition of an incident, the current business object is the specific incident that triggered this business rule.

In other types of expressions, for example, toolbar expressions, the current business object is the business object whose workspace contains the toolbar. For every kind of expression, there is a current business object that makes sense for that expression.

If an expression does not have a relationship specifier, the field name refers to the current business object. For example, $(Status) refers to the Status field of the current business object.

The one exception is LDAP expressions. They do not refer to business object fields.  Instead, they refer to fields of the structures in an LDAP model. For more information, see Configuring LDAP Settings.

Referencing a Field in the Current Business Object

The simplest field reference is a field name. To reference a field within the current business object, refer to the name of the field. You can use a field reference alone, as in the first example below, or put field references inside of an expression, as in the second example below. If the field reference does not have square brackets in front of it, it refers to the current object.

$(FieldName)

$(PrimaryCost + SecondaryCost)

For example, if you are in the Incident business object, to reference the Service field, use the syntax:

$(Service)

You can also reference a field in the current business object in business rules. For example, the following business rule sets the ActualService field to the value of the Service field in the Incident business object whenever the Service field is changed. The value of the ActualService field is computed by an expression:

Example of Referencing a Field within the Current Business Object

Using Relationship Specifiers

•Referencing a Field in a Related Business Object

•Accessing a Field that is Referenced by a Link Field in the Business Object

•Referencing a Business Object Using an Absolute Field Reference

•Accessing a Field from the Other Business Object

•Using Object Matching to Reference a Specific Value of a Business Object

•Referencing a Constrained Validation List for a Business Object

Referencing a Field in a Related Business Object

You can reference a related business object through a relationship or through a link field. For information about using link fields, see Accessing a Field that is Referenced by a Link Field in the Business Object.

•About Related Business Objects

•About Empty Internal Reference Names

•Referencing a Remote Related Business Object

•Using an Internal Reference Name to Access a Business Object Through a Relationship

•Example of Referencing a Related Business Object

About Related Business Objects

To access a related business object through a relationship, the relationship must be one-to-one or many-to-one to remove ambiguity. That is, the expression expects to find at the most one matching child record for the corresponding relationship. At most, one related business object must be found for a given business object.

Use the following syntax to reference a related business object:

$([BusinessObjectName#SubObjectName.InternalReferenceName]FieldName)

where BusinessObjectName#SubObjectName.InternalReferenceName refers to a relationship. Anything in square brackets is a relationship specifier.

where BusinessObjectName#SubObjectName is the name of the business object that the relationship references. The InternalReferenceName specifies the relationship to the business object if there is more than one.

About Empty Internal Reference Names

You must always specify the internal reference name. However, if you have an older expression that does not specify the internal reference name, that older expression will still work unless you make any changes to it. Once you make changes to it, you can no longer use it without the internal reference name. You cannot create any new relationships that have a null reference name. See Using Relationships.

You must specify an internal reference name in a relationship specifier if the relationship has an internal reference name. If you do not specify an internal reference name, the system assumes that you are specifying a relationship with a null reference name. A relationship specifier with an internal reference name can only refer to the relationship with that internal reference name.  A relationship specifier without an internal reference name can only refer to the relationship with an empty or a null internal reference name. (In previous releases, you could leave the internal reference name blank and the system would use any internal reference name.)

If the internal reference name is empty, the business object name must still end with a period. An example is: [Task#Assignment.]Owner.

If a relationship specifier has a non-empty internal reference name, it must be explicitly used in any references that use that expression.  A business object reference without an internal reference name cannot use a relationship with a named internal reference name.

For example, if you enter [Incident#.], the system looks for a relationship from the current business object (in this case, incident) that has an empty internal reference name field; however, the internal reference name field is required, and therefore it cannot find one. (In previous releases, it would look for any relationship that matched and used that.) You must enter an internal reference name, such as [Incident#.name].

Therefore, if you enter something like [Incident#.] in a business rule, it fails.  

Referencing a Remote Related Business Object

You can use more than one relationship specifier to specify a path for a field reference to a remote related business object. Each relationship specifier is enclosed in square brackets, specifying a multi-hop path to the field:

[RelSpecifier1][RelSpecifier2][RelSpecifier3]FieldName

Using an Internal Reference Name to Access a Business Object Through a Relationship

To access a related business object through a relationship, use this form [BusinessObjectName#SubObjectName.InternalReferenceName], where:

•BusinessObjectName#SubObjectName is the business object name (ending with or containing #) for the related business object and ends with a period. An example is: Task#Assignment.. The # separates the name of the business object from the name of the subobject.

•For regular business objects, the BusinessObjectName is of the form [BusinessObjectName#.], for example, [Problem#.].

•For group member or sub business objects, the BusinessObjectName is of the form [BusinessObjectName#SubObjectName.], for example, [Profile#Employee.].

•InternalReferenceName distinguishes one relationship from another. There are times when there is more than one relationship between the same parent and child business objects (for example, incident to employee). In such cases, the system uses the internal reference name of the relationship to distinguish between the relationships. This parameter is specified after the period.

The internal reference name is specified in the Internal Reference Name field on the Relationships tab of the business object. An example is [Problem#.ProblemAssocProblemWorkaround].

Example of a Relationship with the Problem Business Object

Example of Referencing a Related Business Object

Use this type of syntax in the Form Editor to bring in values from a related business object (for example, the EmployeeLocation field from the Employee business object):

Example of Accessing a Value from a Related Business Object

Accessing a Field that is Referenced by a Link Field in the Business Object

You can use link fields to refer to related objects. Link fields are associated with relationships and are an alternate form of reference. To access a related object through a link field, use the relationship specifier [link:LinkField]. This must be used from the business object containing the link field; you cannot reference remote link fields.

To access a field that is referenced by a link in a business object, use the following syntax:

$([link:LinkField]FieldName)

For example, the OrgUnitLink field in the Incident business object points to a corresponding organizational unit record. To reference the value of the Name field of the organizational unit record by means of the OrgUnitLink field, use the following expression:

$([link:OrgUnitLink]Name)

You can use this syntax in the following editing rule, to set the organization unit ID of the incident:

Example of Accessing a Field Referenced by a Link

Here is another example:

$("9"+[link:ProfileLink]Phone1)

This returns a phone number from a related business object, prefixed by a number 9.

Referencing a Business Object Using an Absolute Field Reference

Absolute references, which are another way of referencing a business object, use this syntax: 

[^BusinessObjectName#]FieldName

Use an absolute reference to return the value of the field regardless of the current business object.  This syntax can use a constraint which is a "where" clause followed by an expression. For example:

[^BusinessObjectName# where FieldValue == value]FieldName

such as

[^Incident# where IncidentNumber == 123456] Category

In this example, the system finds the particular incident with an incident number of 123456 and returns it and then you can reference the Category field. If the "where" clause returns more than one business object, then this fails.

An alternate syntax is this:

[^BusinessObjectName# object LinkField]

such as

[^Incident# object RecID]

where RecID is the RecID of a business object, which is normally specified by a link field.

This syntax is mainly designed for integration scenarios.

Accessing a Field from the Other Business Object

Most expressions that are focused on the relationship between one business object and another have what is known as the other business object. For example, editing business rules that have link fields have other business objects.

Many, but not all, expressions also have an other business object. The expressions that have other business objects are those where there is a related business object that is associated with the editing business rule for the expression. (Only editing business rules have an other business object; however, other expressions can have an other business object, such as the Send Email and Insert Child Object quick actions or the Condition field under the Relationships tab.)

For example, the following editing rule is for a link field that associates an incident with an owner team. The current object is the specific incident and the other object is the Team business object. The other object is referred to by using the relationship specifier [OtherObject].

Below, OwnerTeam is a link field and the OwnerTeam field is referring to another business object.

Example of Using an "Other" Object in an Editing Rule

In an editing business rule, whenever the field to be set is a validated field, the other object refers to the validation business object of the validated field. You can use the other object syntax to refer to fields of the validation business object. This is how you can access validation lists with additional information. Use the following syntax:

$([OtherObject]FieldName)

For example:

$([OtherObject]PrimaryEmail)

This returns a pick list called OtherObject in reference to the PrimaryEmail field in the business object. You can only use this in editing business rules.

For example, if you are in an incident and want to access the TeamEmail value for the OwnerTeam currently set for the incident record, first ensure that the OwnerTeam field in the incident is configured to be validated. (To see if the field is validated, go to the Fields tab of the business object, select the OwnerTeam field, and under the Pick List category, see if the Validated field is checked.) In this example, the OwnerTeam field in the incident is validated using the named validation list Team of StandardUserTeam used in Incident.

Accessing a Field from a Validated Business Object Example 1

Second, (with the OwnerTeam field validation in place), define an editing rule against the OwnerTeam field in the incident, so that when this field is changed, the rule returns the field value of the validated business object (that is, the other object). See the following example:

Accessing a Field from a Validated Business Object Example 2

There are two special cases of other business objects that have special syntax:

• In an object matching expression, [MatchedObject] refers to an object that has been matched.

•In a pick list constraint, [ValidationList] refers to the validation object.

Using Object Matching to Reference a Specific Value of a Business Object

$([MatchedObject]FieldName)

This syntax is only used within the context of object matching.

For example, consider the Link and Resolve button used in incident object matching. It links a knowledge article to the current incident record and resolves the incident:

Matched Object Example

In the example, the fields on the left side are from the business object referencing the object matching definition (in this example, the Incident business object), whereas the $([MatchedObject]Resolution) expression on the right side references the field of the business object from object matching (that is, the Resolution field from the Knowledge business object.)

In this example, when the user clicks the Link and Resolve button, the system populates the Resolution field in the incident with the value of the Resolution field from the Knowledge business object (that is, the matched object).

Referencing a Constrained Validation List for a Business Object

To define a constrained validation list (also called a pick list), use the following syntax within the context of the named validation list definition:

$([ValidationList]FieldName)

Typically the values from one validated field are constrained based on the value of another field in the same business object. For example, the JobTitle field in the Employee business object is constrained based on the value of the department selected for the employee.

To define such a validation list, do the following:

1.From the Configuration Console, click Build > Pick Lists to open the Pick Lists workspace.

2.Open a pick list.

3.In the Constraints area, enter the following:

•In the first field, select a field name from the drop-down list.

•In the second field, select Equal to from the drop-down list.

•In the third field, enter $([ValidationList] FieldName>), where FieldName is the name of a field in the business object.

Defining a Constrained Validation List Example

In this example, the values in the first field come from the validation business object. The business object is JobTitle (as indicated in the Get list data from drop-down list).

The $([ValidationList]Department) expression references the field from the business object, which utilizes this named validation list. In this case, the named validation list is Employee business object.

With this configuration, the job titles that can be selected for the employee are based on the department value that was previously selected. The department value from the employee is then used to determine the job title records with the same department name and return the constrained results accordingly.

To reference the named validation list across other business objects, use the $([ValidationList]FieldName) syntax (instead of $(FieldName)). For example, if there is a new business object that needs to implement the same constrained validation list, use the same named validation list for that business object.

Using Field Qualifiers

Field qualifiers are keywords after a colon.

•Referencing a Translated Value of a Business Object Field

•Referencing the Original Value of a Business Object

Referencing a Translated Value of a Business Object Field

To return information from an expression in the culture of the current browser, use this syntax:

FieldName:language

To return information from an expression in another culture, use this syntax:

FieldName:language ("CultureCode")

For example:

Status:language ("fr-FR")

To see a list of supported languages and cultures, see Available Languages and Cultures.

Referencing the Original Value of a Business Object

To reference a business object in an expression with its original, pre-transaction value (as opposed to its updated value), use this syntax:

[BusinessObjectName#.InternalReferenceName]FieldName:original

To reference a business object in an expression with its updated, post-transaction value, use this syntax:

[BusinessObjectName#.InternalReferenceName]FieldName

For example, if you have changed the Status field from open to resolved, the expression would normally use the status of resolved. However, to reference the original status of open, use this syntax:

[BusinessObjectName#.InternalReferenceName]FieldName:original

For example:

[Task#.name]Status:original

Use this syntax when you need to reference the transition (that is, the beginning and ending values) and not just the ending value. For example, if you want to do something every time a task moves from open status to resolved status, you could set a rule, but you could set a different rule every time a task goes from logged status directly to resolved status.